RC docs-sync: daily Claude-authored doc PRs (experimental rollout, wordpress-seo)#388
Merged
enricobattocchi merged 5 commits intomainfrom Apr 28, 2026
Merged
RC docs-sync: daily Claude-authored doc PRs (experimental rollout, wordpress-seo)#388enricobattocchi merged 5 commits intomainfrom
enricobattocchi merged 5 commits intomainfrom
Conversation
Adds the plumbing for a daily GitHub Action that polls Yoast product repos for new RC tags, runs a Claude agent against the developer-portal docs, and opens draft PRs where doc updates are warranted. Scope for this first phase: Yoast SEO (free) only. More products added iteratively by extending AGENT_MAP.md and the PRODUCTS dict in the workflow. Architecture: - No GitHub App or PAT required; product repos are public so anonymous cloning works and all writes to this repo use GITHUB_TOKEN. - Never writes to main; state lives in tracking-issue comments, identified by a machine-readable marker embedded in every run-summary comment. - Cloudflare Pages preview deploy on PR is the per-PR validation. - PRs are never auto-merged; branch protection's PR-review rule is the gate. Validated through three manual spikes (narrow positive, negative hotfix, multi-file new feature) plus end-to-end dry-runs of the orchestration prompt. Activation requirements (handled post-merge, see PR body): create a tracking issue, set TRACKING_ISSUE_WORDPRESS_SEO repo variable, set ANTHROPIC_API_KEY secret (coordinated with devops). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying yoast-developer with
|
| Latest commit: |
075164f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1a0ce4d1.yoast-developer.pages.dev |
| Branch Preview URL: | https://rc-docs-sync-proposal.yoast-developer.pages.dev |
Two refinements in response to review: - Agent now detects and reports "AGENT_MAP.md coverage gaps" during every RC run. A coverage gap is a hunk that looks like public surface (new apply_filters / do_action, new REST route, new top-level src/<subsystem>/ file with public classes) whose path or symbol isn't covered by any area's source_paths or symbol_namespaces. Listed in the run-summary comment under a "Coverage gaps observed" section only when present. Informational; does not block the run. Turns every RC into a free audit of the map. - Removed AI Brand Insights from AGENT_MAP.md's Product table and from the `ai` area's product list. Rationale: the developer portal currently has no feature-spec docs for it (only a changelog), so every docs-sync run on the product would reliably produce zero PRs. Keeping it in the map would waste compute and review attention on unambiguously no-op runs. Added a note in the `ai` area describing how to re-add it (product table entry plus source paths for ai-insights-api and ai-insights-frontend, plus a split-product rule) when/if feature docs land. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drop the "off-by-default" flag from the duplicate-post area. It has docs in this repo (docs/duplicate-post/**) and an active release cadence in Yoast/duplicate-post, so there's no reason to treat it differently from any other documented product. Simplify the agent's "never touch" rule to docs/development/** only — the per-area docs_paths matching already ensures docs/duplicate-post/ is only touched when PRODUCT=duplicate-post. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The product has no feature docs in this repo and will not gain any, so per-product notes about how to re-integrate it later are noise. Replaced the two AI-Brand-Insights-specific notes (Product table + ai area) with a generic rule stating only products with feature docs belong in the table. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the placeholder shell line with an anthropics/claude-code-action@v1
step. To make it possible to use a `uses:` step inside the per-RC processing
loop, the workflow is reorganized into two jobs:
- resolve: runs the Python queue-resolution + first-run seeding logic and
emits the queue as a JSON output for downstream matrix consumption.
- process: matrix over the queue (max-parallel=1 to keep PR creation
serial for now), one job per (product, rc_tag) pair. Each job clones
the source repo at the RC and previous-release tags, builds the diff
bundle + symbol index + changelog source, then either posts a no-op
summary (if the filtered diff is empty) or invokes the Claude agent.
The agent step:
- Reads .github/claude-agent/run.md as its instructions.
- Has env vars PRODUCT, RC_TAG, DISPLAY_NAME, BUNDLE_DIR, TRACKING_ISSUE,
PREV_RELEASE, WORKFLOW_RUN_URL set explicitly.
- Has a narrow allowed-tools list: Read/Grep/Glob/Edit/Write on the
workspace, plus Bash for git, gh, and a handful of read-only utilities.
- Defaults to claude-sonnet-4-6, max-turns 50.
GITHUB_TOKEN is picked up automatically by the action, so the agent can
push branches, open PRs, label them, and post issue comments via gh
without further configuration.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
enricobattocchi
changed the title
enricobattocchi
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships an experimental daily workflow that polls
Yoast/wordpress-seofor new RC tags, runs a Claude agent against the developer-portal docs, and opens draft PRs when docs need updating. Going live for Yoast SEO (free) first — once real RCs have run through it and the output looks good, we expand to the other documented products.What this PR adds
AGENT_MAP.md(repo root) — source of truth for the feature-area taxonomy: docs paths per area, per-product source-path globs, symbol namespaces, and the Product → source repo table (with human-readable display names). The agent loads this at runtime to triage an RC diff and route proposed changes into PRs..github/claude-agent/run.md— the agent orchestration prompt. Triage + authoring + PR-creation flow, style rules, authoring discipline, PR title format, and the machine-readable marker for the run-summary comment (which doubles as state for the next run). Includes a coverage-gap self-reporting step so every RC run surfaces public surface observed in the diff but not yet covered byAGENT_MAP.md..github/workflows/rc-docs-sync.yml— the daily workflow. Two jobs: aresolvejob that builds the queue of (product, rc_tag) pairs to process, and aprocessjob that fans out as a matrix and invokes the Claude agent per item.schedule: 0 6 * * *+workflow_dispatchfor manual backfill.How it works (per daily run)
wordpress-seoright now), query the product repo's tags via the public GitHub API — anonymous, no token.Yoast/wordpress-seoat the RC tag (anonymous).readme.txtchangelog entry.docs/tree.anthropics/claude-code-action@v1, modelclaude-sonnet-4-6) with.github/claude-agent/run.md. The agent triages, opens one PR per affected feature area (branchrc-sync/<product>/<rc_tag>/<area>, titleYoast SEO <base-version> — docs(<area>): <title>), surfaces anyAGENT_MAP.mdcoverage gaps it observed, and posts a summary comment back to the tracking issue. The comment's marker is the state for tomorrow's run.Why this architecture
GITHUB_TOKEN. The only external secret isANTHROPIC_API_KEY.main. State lives in tracking-issue comments (not a committed state file), so the workflow is indifferent tomainbeing protected.yarn buildlocally — broken Docusaurus builds fail the CF Pages deploy and surface on the PR.GITHUB_TOKENcan't approve PRs, and the workflow never callsgh pr merge. Human reviewer is the sole merge gate.Validation
Three manual spikes were run against past RCs of
Yoast/wordpress-seo:wpseo_llmstxt_link_descriptionfilter in 26.3-RC1llms-txt, authoring semantically matched the ground-truth doc PR.schema-aggregator(3 new docs +sidebars.js) and a bonus catch forrobots-txt(Schemamap directive +wpseo_disable_robots_schemamapfilter). The robots-txt update is something the team had to address in follow-up doc commits after the original schema-aggregator PR — the agent would have caught it at RC time.End-to-end dry-runs of the orchestration prompt on Spikes A and C produced the expected
proposed-docs.patch,proposed-sidebars.patch, andrun-summary.mdartifacts (with correct marker, correct PR-title format, correct area placement).Activation status
TRACKING_ISSUE_WORDPRESS_SEO=390ANTHROPIC_API_KEYanthropics/claude-code-action@v1,claude-sonnet-4-6, narrow allowlist)workflow_dispatchvalidation against a past RC27.6-RC1once that tag landsKnown follow-ups (not blocking)
PRODUCTSdict in the workflow currently lists onlywordpress-seo. Adding a product = add slug + source repos + display name + tracking-issue var name there, plus create its tracking issue + repo variable.Rollout plan
wordpress-seoonly.wordpress-seo-premiumandwordpress-seo-local.wpseo-news,wpseo-video,wpseo-woocommerce,shopify-seo,duplicate-post. Each is a pure config addition.🤖 Planning and artifact drafting assisted by Claude.